home *** CD-ROM | disk | FTP | other *** search
/ Aminet 32 / Aminet 32 (1999)(Schatztruhe)[!][Aug 1999].iso / Aminet / dev / lang / Python151_Src.lha / Python1.5_Source / README < prev    next >
Text File  |  1998-11-22  |  34KB  |  829 lines
  1.  
  2. [Note: this is the README file from the original Python Source Archive,
  3.  from www.python.org]
  4.  
  5.  
  6.  
  7. This is Python release 1.5.1
  8. ============================
  9.  
  10. This version is officially released on Tuesday, April 14, 1997.  It is
  11. mostly a bugfix release on Python 1.5.
  12.  
  13.  
  14. What's new in this release?
  15. ---------------------------
  16.  
  17. See the Misc/NEWS file.  Nothing spectacular this time, only small
  18. changes (as you would expect from a release called "1.5.1").
  19.  
  20. One big organizational change: the documentation sources have been
  21. unbundled.  We will release a version of the Doc subtree separately,
  22. but probably not simultaneously with the source release.
  23.  
  24.  
  25. If you don't read instructions
  26. ------------------------------
  27.  
  28. Congratulations on getting this far. :-)
  29.  
  30. To start building right away (on UNIX): type "./configure" in the
  31. current directory and when it finishes, type "make".  The section
  32. Build Instructions below is still recommended reading. :-)
  33.  
  34.  
  35. What is Python anyway?
  36. ----------------------
  37.  
  38. Python is an interpreted object-oriented programming language, and is
  39. often compared to Tcl, Perl, Java or Scheme.  To find out more, point
  40. your browser to http://www.python.org/.
  41.  
  42.  
  43. A modest plug
  44. -------------
  45.  
  46. ************************************************************************
  47. * Without your support, I won't be able to continue to work on Python! *
  48. ************************************************************************
  49.  
  50. If you use Python, please consider joining the Python Software
  51. Activity (PSA).  See http://www.python.org/psa/.
  52.  
  53. Organizations that make heavy use of Python are especially encouraged
  54. to become corporate members!
  55.  
  56.  
  57. How do I learn Python?
  58. ----------------------
  59.  
  60. The official tutorial is still a good place to start (in the Doc
  61. directory as tut.tex; and http://www.python.org/doc/tut/tut.html).
  62. Aaron Watters wrote a second tutorial, that may be more accessible for
  63. some: http://www.wcmh.com/uworld/archives/95/tutorial/005.html.  Both
  64. tutorials (as well as most other sources) assume that you already know
  65. how to program -- if you'd like to write "Python for Dummies", I know
  66. a publisher who would like to talk to you...
  67.  
  68. There are now also several books on Python.  While these are still
  69. based on Python 1.3 or 1.4, the information in them is still 99%
  70. correct.  The first two books, both first published in October 1996
  71. and both including a CD-ROM, form excellent companions to each other:
  72.  
  73.     Internet Programming with Python
  74.     by Aaron Watters, Guido van Rossum, and James Ahlstrom
  75.     MIS Press/Henry Holt publishers
  76.     ISBN: 1-55851-484-8
  77.  
  78.     Programming Python
  79.     by Mark Lutz
  80.     O'Reilly & Associates
  81.     ISBN: 1-56592-197-6
  82.  
  83. If you can read German, try:
  84.  
  85.     Das Python-Buch
  86.     by Martin von Loewis and Nils Fischbeck
  87.     Addison-Wesley-Longman, 1997
  88.     ISBN: 3-8273-1110-1
  89.  
  90.  
  91. Copyright issues
  92. ----------------
  93.  
  94. Python is COPYRIGHTED but free to use for all.  See the full copyright
  95. notice at the end of this file and in the file Misc/COPYRIGHT.
  96.  
  97. The Python distribution is *not* affected by the GNU Public Licence
  98. (GPL).  There are interfaces to some GNU code but these are entirely
  99. optional and no GNU code is distributed with Python.
  100.  
  101.  
  102. Build instructions
  103. ==================
  104.  
  105. Before you can build Python, you must first configure it.
  106. Fortunately, the configuration and build process has been streamlined
  107. for most Unix installations, so all you have to do is type a few
  108. commands, optionally edit one file, and sit back.  There are some
  109. platforms where things are not quite as smooth; see the platform
  110. specific notes below.  If you want to build for multiple platforms
  111. sharing the same source tree, see the section on VPATH below.
  112.  
  113. You start by running the script "./configure", which figures out your
  114. system configuration and creates several Makefiles.  (It takes a
  115. minute or two -- please be patient!)  When it's done, you are ready to
  116. run make.  You may want to pass options to the configure script -- see
  117. the section below on configuration options and variables.
  118.  
  119. To build Python, you normally type "make" in the toplevel directory.
  120. This will recursively run make in each of the subdirectories Parser,
  121. Objects, Python and Modules, creating a library file in each one.  The
  122. executable of the interpreter is built in the Modules subdirectory and
  123. moved up here when it is built.  If you want or need to, you can also
  124. chdir into each subdirectory in turn and run make there manually (do
  125. the Modules subdirectory last!).
  126.  
  127. Once you have built an interpreter, see the subsections below on
  128. testing, configuring additional modules, and installation.  If you run
  129. in trouble, see the next section.
  130.  
  131.  
  132. Troubleshooting
  133. ---------------
  134.  
  135. See also the platform specific notes in the next section.
  136.  
  137. If recursive makes fail, try invoking make as "make MAKE=make".
  138.  
  139. If you run into other trouble, see section 3 of the FAQ
  140. (http://grail.cnri.reston.va.us/cgi-bin/faqw.py or
  141. http://www.python.org/doc/FAQ.html) for hints on what can go wrong,
  142. and how to fix it.
  143.  
  144. If you rerun the configure script with different options, remove all
  145. object files by running "make clean" before rebuilding.  Believe it or
  146. not, "make clean" sometimes helps to clean up other inexplicable
  147. problems as well.  Try it before sending in a bug report!
  148.  
  149. If the configure script fails or doesn't seem to find things that
  150. should be there, inspect the config.log file.  When you fix a
  151. configure problem, be sure to remove config.cache!
  152.  
  153. If you get a warning for every file about the -Olimit option being no
  154. longer supported, you can ignore it.  There's no foolproof way to know
  155. whether this option is needed; all I can do is test whether it is
  156. accepted without error.  On some systems, e.g. older SGI compilers, it
  157. is essential for performance (specifically when compiling ceval.c,
  158. which has more basic blocks than the default limit of 1000).  If the
  159. warning bothers you, edit the Makefile to remove "-Olimit 1500" from
  160. the OPT variable.
  161.  
  162.  
  163. Platform specific notes
  164. -----------------------
  165.  
  166. (Some of these may no longer apply.  If you find you can build Python
  167. on these platforms without the special directions mentioned here, let
  168. me know so I can remove them!)
  169.  
  170. 64-bit platforms: The modules audioop, imageop and rgbimg don't work.
  171.     Don't try to enable them in the Modules/Setup file.  They
  172.     contain code that is quite wordsize sensitive.  (If you have a
  173.     fix, let me know!)
  174.  
  175. Solaris: When using Sun's C compiler with threads, at least on Solaris
  176.     2.5.1, you need to add the "-mt" compiler option (the simplest
  177.     way is probably to specify the compiler with this option as
  178.     the "CC" environment variable when running the configure
  179.     script).
  180.  
  181. Linux:  On Linux version 1.x, once you've built Python, use it to run
  182.     the regen script in the Lib/linux1 directory.  Apparently
  183.     the files as distributed don't match the system headers on
  184.     some Linux versions.  (The "h2py" command refers to
  185.     Tools/scripts/h2py.py.)  The modules distributed for Linux 2.x
  186.     should be okay.  Shared library support now works by default
  187.     on ELF-based x86 Linux systems.  (Note: when you change the
  188.     status of a module from static to shared, you must remove its
  189.     .o file or do a "make clean".)
  190.  
  191.     Under RedHat Linux 5.0, if upgraded from a previous version,
  192.     remove the LinuxThreads packages.  This is needed because
  193.     LinuxThreads conflicts with the new thread support provided by
  194.     glibc.  Before running Python's configure script, use the
  195.     following commands as root (version numbers may differ; these
  196.     are from a stock 4.2 install):
  197.  
  198.     % rpm -qa | grep ^linuxthread
  199.     linuxthreads-0.5-1
  200.     linuxthreads-devel-0.5-1
  201.     % rpm -e linuxthreads linuxthreads-devel
  202.  
  203.     While Python only needs this to be done to allow thread
  204.     support to be included, the conflicts these packages create
  205.     with the new glibc may cause other packages which use threads
  206.     to fail as well, so their removal is a good idea regardless of
  207.     how you configure python.
  208.  
  209.     Also under RedHat Linux 5.0, the crypt module now needs the
  210.     -lcrypt option.  Uncomment this flag in Modules/Setup, or
  211.     comment out the crypt module in the same file.
  212.  
  213. DEC Unix: When enabling threads, use --with-dec-threads, not
  214.     --with-thread.  When using GCC, it is possible to get an
  215.     internal compiler error if optimization is used.  This was
  216.     reported for GCC 2.7.2.3 on selectmodule.c.  Manually compile
  217.     the affected file without optimization to solve the problem.
  218.  
  219. AIX:    A complete overhaul of the shared library support is now in
  220.     place.  See Misc/AIX-NOTES for some notes on how it's done.
  221.     (The optimizer bug reported at this place in previous releases
  222.     has been worked around by a minimal code change.)
  223.  
  224. Minix:  When using ack, use "CC=cc AR=aal RANLIB=: ./configure"!
  225.  
  226. SCO:    The following only apply to SCO 3; Python builds out of the box
  227.     on SCO 5 (or so I've heard).
  228.  
  229.     1) Everything works much better if you add -U__STDC__ to the
  230.     defs.  This is because all the SCO header files are broken.
  231.     Anything that isn't mentioned in the C standard is
  232.     conditionally excluded when __STDC__ is defined.
  233.  
  234.     2) Due to the U.S. export restrictions, SCO broke the crypt
  235.     stuff out into a separate library, libcrypt_i.a so the LIBS
  236.     needed be set to:
  237.  
  238.         LIBS=' -lsocket -lcrypt_i'
  239.  
  240. SunOS 4.x: When using the standard "cc" compiler, certain modules may
  241.     not be compilable because they use non-K&R syntax.  You should
  242.     be able to get a basic Python interpreter by commenting out
  243.     such modules in the Modules/Setup file, but I really recommend
  244.     using gcc.
  245.  
  246.     When using the SunPro C compiler, you may want to use the
  247.     '-Xa' option instead of '-Xc', to enable some needed non-ANSI
  248.     Sunisms.
  249.  
  250. NeXT:   To build fat binaries, use the --with-next-archs switch
  251.     described below.
  252.  
  253. QNX:    Chris Herborth (chrish@qnx.com) writes:
  254.     configure works best if you use GNU bash; a port is available on
  255.     ftp.qnx.com in /usr/free.  I used the following process to build,
  256.     test and install Python 1.5 under QNX:
  257.  
  258.     1) SHELL=/usr/local/bin/bash CC=cc CFLAGS="-5 -O" RANLIB=: \
  259.         bash ./configure --verbose --without-gcc --with-libm=""
  260.  
  261.     2) copy Modules/Setup.in to Modules/Setup; edit Modules/Setup to
  262.        activate everything that makes sense for your system... tested
  263.        here at QNX with the following modules:
  264.  
  265.         regex reop pcre posix signal readline array cmath math strop
  266.         struct time operator _locale fcntl pwd grp crypt select socket
  267.         errno termios audioop imageop rgbimg md5 timing rotor syslog
  268.         new gdbm soundex binascii parser cStringIO cPickle zlib curses
  269.  
  270.     3) SHELL=/usr/local/bin/bash make SHELL=/usr/local/bin/bash
  271.  
  272.     4) SHELL=/usr/local/bin/bash make SHELL=/usr/local/bin/bash test
  273.  
  274.        The socket, strftime and possibly gdbm tests might fail in the
  275.        test harness; going through them by hand shows that they work.
  276.        A good exercise for the reader: make these work "out of the box".
  277.  
  278.     5) SHELL=/usr/local/bin/bash make SHELL=/usr/local/bin/bash install
  279.  
  280.     If you get SIGSEGVs while running Python (I haven't yet, but I've
  281.     only run small programs and the test cases), you're probably running
  282.     out of stack; the default 32k could be a little tight.  To increase
  283.     the stack size, edit the Makefile in the Modules directory to read:
  284.     LDFLAGS = -N 48k
  285.  
  286. Cray T3E: Konrad Hinsen writes:
  287.     1) Don't use gcc. It compiles Python/graminit.c into something that
  288.        the Cray assembler doesn't like. Cray's cc seems to work fine.
  289.     2) Uncomment modules md5 (won't compile) and audioop (will crash
  290.        the interpreter during the test suite).
  291.     If you run the test suite, two tests will fail (rotate and binascii),
  292.     but these are not the modules you'd expect to need on a Cray.
  293.  
  294. SGI:    SGI's standard "make" utility (/bin/make or /usr/bin/make)
  295.     does not check whether a command actually changed the file it
  296.     is supposed to build.  This means that whenever you say "make"
  297.     it will redo the link step.  The remedy is to use SGI's much
  298.     smarter "smake " utility (/usr/sbin/smake), or GNU make.  If
  299.     you set the first line of the Makefile to #!/usr/sbin/smake
  300.     smake will be invoked by make (likewise for GNU make).
  301.  
  302.     A bug in the MIPSpro 7.1 compiler's optimizer seems to break
  303.     Modules/pypcre.c.  The short term solution is to compile it
  304.     without optimization.  The bug appears to be fixed in version
  305.     7.2.1 of the compiler.
  306.  
  307. OS/2:   If you are running Warp3 or Warp4 and have IBM's VisualAge C/C++
  308.         compiler installed, just change into the pc\os2vacpp directory
  309.         and type NMAKE.  Threading and sockets are supported by default
  310.         in the resulting binaries of PYTHON15.DLL and PYTHON.EXE.
  311.  
  312.  
  313. Configuring additional built-in modules
  314. ---------------------------------------
  315.  
  316. You can configure the interpreter to contain fewer or more built-in
  317. modules by editing the file Modules/Setup.  This file is initially
  318. copied (when the toplevel Makefile makes Modules/Makefile for the
  319. first time) from Setup.in; if it does not exist yet, make a copy
  320. yourself.  Never edit Setup.in -- always edit Setup.  Read the
  321. comments in the file for information on what kind of edits you can
  322. make.  When you have edited Setup, Makefile and config.c in Modules
  323. will automatically be rebuilt the next time you run make in the
  324. toplevel directory.  (When working inside the Modules directory, use
  325. "make Makefile; make".)
  326.  
  327. The default collection of modules should build on any Unix system, but
  328. many optional modules should work on all modern Unices (e.g. try dbm,
  329. nis, termios, timing, syslog, curses, new, soundex, parser).  Often
  330. the quickest way to determine whether a particular module works or not
  331. is to see if it will build: enable it in Setup, then if you get
  332. compilation or link errors, disable it -- you're missing support.
  333.  
  334. On SGI IRIX, there are modules that interface to many SGI specific
  335. system libraries, e.g. the GL library and the audio hardware.
  336.  
  337. For SunOS and Solaris, enable module "sunaudiodev" to support the
  338. audio device.
  339.  
  340. In addition to the file Setup, you can also edit the file Setup.local.
  341. (the makesetup script processes both).  You may find it more
  342. convenient to edit Setup.local and leave Setup alone.  Then, when
  343. installing a new Python version, you can copy your old Setup.local
  344. file.
  345.  
  346.  
  347. Setting the optimization/debugging options
  348. ------------------------------------------
  349.  
  350. If you want or need to change the optimization/debugging options for
  351. the C compiler, assign to the OPT variable on the toplevel make
  352. command; e.g. "make OPT=-g" will build a debugging version of Python
  353. on most platforms.  The default is OPT=-O; a value for OPT in the
  354. environment when the configure script is run overrides this default
  355. (likewise for CC; and the initial value for LIBS is used as the base
  356. set of libraries to link with).
  357.  
  358.  
  359. Testing
  360. -------
  361.  
  362. To test the interpreter that you have just built, type "make test".
  363. This runs the test set twice (once with no compiled files, once with
  364. the compiled files left by the previous test run).  The test set
  365. produces some output.  You can generally ignore the messages about
  366. skipped tests due to an optional feature that can't be imported (if
  367. you want to test those modules, edit Modules/Setup to configure them).
  368. If a messages is printed about a failed test or a traceback or core
  369. dump is produced, something's wrong.  On some Linux systems (those
  370. that are not yet using glibc 6), test_strftime fails due to a
  371. non-standard-compliant implementation of strftime() in the C library.
  372. Please ignore this, or upgrade to glibc version 6.
  373.  
  374. IMPORTANT: If the tests fail and you decide to mail a bug report,
  375. *don't* include the output of "make test".  It is useless.  Run the
  376. test that fails manually, as follows:
  377.  
  378.     python ../Lib/test/test_whatever.py
  379.  
  380. (substituting the top of the source tree for .. if you built in a
  381. different directory).  This runs the test in verbose mode.
  382.  
  383.  
  384. Installing
  385. ----------
  386.  
  387. To install the Python binary, library modules, shared library modules
  388. (see below), include files, configuration files, and the manual page,
  389. just type
  390.  
  391.     make install
  392.  
  393. This will install all platform-independent files in subdirectories the
  394. directory given with the --prefix option to configure or the 'prefix'
  395. Make variable (default /usr/local), and all binary and other
  396. platform-specific files in subdirectories if the directory given by
  397. --exec-prefix or the 'exec_prefix' Make variable (defaults to the
  398. --prefix directory).
  399.  
  400. All subdirectories created will have Python's version number in their
  401. name, e.g. the library modules are installed in
  402. "/usr/local/lib/python1.5/" by default.  The Python binary is
  403. installed as "python1.5" and a hard link named "python" is created.
  404. The only file not installed with a version number in its name is the
  405. manual page, installed as "/usr/local/man/man1/python.1" by default.
  406.  
  407. If you have a previous installation of a pre-1.5 Python that you don't
  408. want to replace yet, use
  409.  
  410.     make altinstall
  411.  
  412. This installs the same set of files as "make install" except it
  413. doesn't create the hard link to "python1.5" named "python" and it
  414. doesn't install the manual page at all.
  415.  
  416. The only thing you may have to install manually is the Python mode for
  417. Emacs.  (But then again, more recent versions of Emacs may already
  418. have it!)  This is the file Misc/python-mode.el; follow the
  419. instructions that came with Emacs for installation of site specific
  420. files.
  421.  
  422.  
  423. Configuration options and variables
  424. -----------------------------------
  425.  
  426. Some special cases are handled by passing options to the configure
  427. script.
  428.  
  429. WARNING: if you rerun the configure script with different options, you
  430. must run "make clean" before rebuilding.  Exceptions to this rule:
  431. after changing --prefix or --exec-prefix, all you need to do is remove
  432. Modules/getpath.o.
  433.  
  434. --with(out)-gcc: The configure script uses gcc (the GNU C compiler) if
  435.     it finds it.  If you don't want this, or if this compiler is
  436.     installed but broken on your platform, pass the option
  437.     --without-gcc.  You can also pass "CC=cc" (or whatever the
  438.     name of the proper C compiler is) in the environment, but the
  439.     advantage of using --without-gcc is that this option is
  440.     remembered by the config.status script for its --recheck
  441.     option.
  442.  
  443. --prefix, --exec-prefix: If you want to install the binaries and the
  444.     Python library somewhere else than in /usr/local/{bin,lib},
  445.     you can pass the option --prefix=DIRECTORY; the interpreter
  446.     binary will be installed as DIRECTORY/bin/python and the
  447.     library files as DIRECTORY/lib/python/*.  If you pass
  448.     --exec-prefix=DIRECTORY (as well) this overrides the
  449.     installation prefix for architecture-dependent files (like the
  450.     interpreter binary).  Note that --prefix=DIRECTORY also
  451.     affects the default module search path (sys.path), when
  452.     Modules/config.c is compiled.  Passing make the option
  453.     prefix=DIRECTORY (and/or exec_prefix=DIRECTORY) overrides the
  454.     prefix set at configuration time; this may be more convenient
  455.     than re-running the configure script if you change your mind
  456.     about the install prefix...
  457.  
  458. --with-readline: This option is no longer supported.  To use GNU
  459.     readline, enable module "readline" in the Modules/Setup file.
  460.  
  461. --with-thread: On most Unix systems, you can now use multiple threads.
  462.     To enable this, pass --with-thread.  (--with-threads is an
  463.     alias.)  If the library required for threads lives in a
  464.     peculiar place, you can use --with-thread=DIRECTORY.  NOTE:
  465.     you must also enable the thread module by uncommenting it in
  466.     the Modules/Setup file.  (Threads aren't enabled automatically
  467.     because there are run-time penalties when support for them is
  468.     compiled in even if you don't use them.)  IMPORTANT: run "make
  469.     clean" after changing (either enabling or disabling) this
  470.     option, or you will get link errors!  Note: for DEC Unix use
  471.     --with-dec-threads instead.
  472.  
  473. --with-sgi-dl: On SGI IRIX 4, dynamic loading of extension modules is
  474.     supported by the "dl" library by Jack Jansen, which is
  475.     ftp'able from ftp://ftp.cwi.nl/pub/dynload/dl-1.6.tar.Z.
  476.     This is enabled (after you've ftp'ed and compiled the dl
  477.     library!) by passing --with-sgi-dl=DIRECTORY where DIRECTORY
  478.     is the absolute pathname of the dl library.  (Don't bother on
  479.     IRIX 5, it already has dynamic linking using SunOS style
  480.     shared libraries.)  Support for this feature is deprecated.
  481.  
  482. --with-dl-dld: Dynamic loading of modules is rumoured to be supported
  483.     on some other systems: VAX (Ultrix), Sun3 (SunOS 3.4), Sequent
  484.     Symmetry (Dynix), and Atari ST.  This is done using a
  485.     combination of the GNU dynamic loading package
  486.     (ftp://ftp.cwi.nl/pub/dynload/dl-dld-1.1.tar.Z) and an
  487.     emulation of the SGI dl library mentioned above (the emulation
  488.     can be found at
  489.     ftp://ftp.cwi.nl/pub/dynload/dld-3.2.3.tar.Z).  To
  490.     enable this, ftp and compile both libraries, then call the
  491.     configure passing it the option
  492.     --with-dl-dld=DL_DIRECTORY,DLD_DIRECTORY where DL_DIRECTORY is
  493.     the absolute pathname of the dl emulation library and
  494.     DLD_DIRECTORY is the absolute pathname of the GNU dld library.
  495.     (Don't bother on SunOS 4 or 5, they already have dynamic
  496.     linking using shared libraries.)  Support for this feature is
  497.     deprecated.
  498.  
  499. --with-libm, --with-libc: It is possible to specify alternative
  500.     versions for the Math library (default -lm) and the C library
  501.     (default the empty string) using the options
  502.     --with-libm=STRING and --with-libc=STRING, respectively.  E.g.
  503.     if your system requires that you pass -lc_s to the C compiler
  504.     to use the shared C library, you can pass --with-libc=-lc_s.
  505.     These libraries are passed after all other libraries, the C
  506.     library last.
  507.     
  508. --with-next-archs='arch1 arch2': Under NEXTSTEP, this will build
  509.     all compiled binaries with the architectures listed.  Includes
  510.     correctly setting the target architecture specific resource
  511.     directory.  (This option is not supported on other platforms.)
  512.  
  513. --with-libs='libs': Add 'libs' to the LIBS that the python
  514.     linked against.
  515.  
  516.  
  517. Building for multiple architectures (using the VPATH feature)
  518. -------------------------------------------------------------
  519.  
  520. If your file system is shared between multiple architectures, it
  521. usually is not necessary to make copies of the sources for each
  522. architecture you want to support.  If the make program supports the
  523. VPATH feature, you can create an empty build directory for each
  524. architecture, and in each directory run the configure script (on the
  525. appropriate machine with the appropriate options).  This creates the
  526. necessary subdirectories and the Makefiles therein.  The Makefiles
  527. contain a line VPATH=... which points to directory containing the
  528. actual sources.  (On SGI systems, use "smake -J1" instead of "make" if
  529. you use VPATH -- don't try gnumake.)
  530.  
  531. For example, the following is all you need to build a minimal Python
  532. in /usr/tmp/python (assuming ~guido/src/python is the toplevel
  533. directory and you want to build in /usr/tmp/python):
  534.  
  535.     $ mkdir /usr/tmp/python
  536.     $ cd /usr/tmp/python
  537.     $ ~guido/src/python/configure
  538.     [...]
  539.     $ make
  540.     [...]
  541.     $
  542.  
  543. Note that Modules/Makefile copies the original Setup file to the build
  544. directory if it finds no Setup file there.  This means that you can
  545. edit the Setup file for each architecture independently.  For this
  546. reason, subsequent changes to the original Setup file are not tracked
  547. automatically, as they might overwrite local changes.  To force a copy
  548. of a changed original Setup file, delete the target Setup file.  (The
  549. makesetup script supports multiple input files, so if you want to be
  550. fancy you can change the rules to create an empty Setup.local if it
  551. doesn't exist and run it with arguments $(srcdir)/Setup Setup.local;
  552. however this assumes that you only need to add modules.)
  553.  
  554.  
  555. Building on non-UNIX systems
  556. ----------------------------
  557.  
  558. Building Python for a PC is now a piece of cake!
  559.  
  560. Enter the directory "PC" and read the file "readme.txt".  Most popular
  561. non-Unix PC platforms and compilers are supported (Unix ports to the
  562. PC such as Linux, FreeBSD or Solaris-x86 of course use the standard
  563. Unix build instructions).
  564.  
  565. For the Mac, a separate source distribution will be made available,
  566. for use with the CodeWarrior compiler.  If you are interested in Mac
  567. development, join the PythonMac Special Interest Group
  568. (http://www.python.org/sigs/pythonmac-sig/, or send email to
  569. pythonmac-sig-request@python.org).
  570.  
  571. Of course, there are also binary distributions available for these
  572. platforms -- see http://www.python.org/python/.
  573.  
  574. To port Python to a new non-UNIX system, you will have to fake the
  575. effect of running the configure script manually (for Mac and PC, this
  576. has already been done for you).  A good start is to copy the file
  577. config.h.in to config.h and edit the latter to reflect the actual
  578. configuration of your system.  Most symbols must simply be defined as
  579. 1 only if the corresponding feature is present and can be left alone
  580. otherwise; however RETSIGTYPE must always be defined, either as int or
  581. as void, and the *_t type symbols must be defined as some variant of
  582. int if they need to be defined at all.
  583.  
  584.  
  585.  
  586. Miscellaneous issues
  587. ====================
  588.  
  589. Documentation
  590. -------------
  591.  
  592. All documentation is provided in the subdirectory Doc in the form of
  593. LaTeX files.  In order of importance for new users: Tutorial (tut),
  594. Library Reference (lib), Language Reference (ref), Extending (ext).
  595. Especially the Library Reference is of immense value since much of
  596. Python's power (including the built-in data types and functions!) is
  597. described here.
  598.  
  599. To print the documentation from the LaTeX files, chdir into the Doc
  600. subdirectory, type "make" (let's hope you have LaTeX installed!), and
  601. send the four resulting PostScript files (tut.ps, lib.ps, ref.ps, and
  602. ext.ps) to the printer.  See the README file there.  If you don't have
  603. LaTeX, you can ftp the PostScript files from the ftp archives (see
  604. below).
  605.  
  606. All documentation is also available on-line via the Python web site
  607. (http://www.python.org/, see below).  It can also be downloaded
  608. separately from the ftp archives (see below) in Emacs INFO, HTML or
  609. PostScript form -- see the web site or the FAQ
  610. (http://grail.cnri.reston.va.us/cgi-bin/faqw.py or
  611. http://www.python.org/doc/FAQ.html) for more info.
  612.  
  613.  
  614. Emacs mode
  615. ----------
  616.  
  617. There's an excellent Emacs editing mode for Python code; see the file
  618. Misc/python-mode.el.  Originally written by the famous Tim Peters, it
  619. is now maintained by the equally famous Barry Warsaw
  620. <bwarsaw@cnri.reston.va.us>.  The latest version is online at
  621. ftp://ftp.python.org/pub/emacs/python-mode.el.  As you might expect of
  622. Barry (and even if you don't know what the heck I'm talking about :-),
  623. a configuration file for his cc-mode.el which selects the style used
  624. throughout most Python C source files is also provided; see the file
  625. Misc/ccpy-style.el.
  626.  
  627.  
  628. Web site
  629. --------
  630.  
  631. Python's own web site has URL http://www.python.org/.  Come visit us!
  632. There are a number of mirrors, and a list of mirrors is accessible
  633. from the home page -- try a mirror that's close you you.
  634.  
  635.  
  636. Ftp site
  637. --------
  638.  
  639. Python's own ftp site is ftp://ftp.python.org/pub/python/.  There are
  640. numerous mirrors; the list of mirrors is accessible from
  641. http://www.python.org/.
  642.  
  643.  
  644. Newsgroups
  645. ----------
  646.  
  647. Read comp.lang.python, a high-volume discussion newsgroup about
  648. Python, or comp.lang.python.announce, a low-volume moderated newsgroup
  649. for Python-related announcements.  These are also accessible as
  650. mailing lists, see the next item.
  651.  
  652. Archives are accessible via Deja News; the Python website has a
  653. query form for the archives at http://www.python.org/search/.
  654.  
  655.  
  656. Mailing lists
  657. -------------
  658.  
  659. See http://www.python.org/psa/MailingLists.html for an overview of the 
  660. many Python related mailing lists.
  661.  
  662.  
  663. Bug reports
  664. -----------
  665.  
  666. Bugs are best reported to the comp.lang.python newsgroup (or the
  667. Python mailing list) -- see the section "Newsgroups" above.  Before
  668. posting, check the newsgroup archives (see above) to see if your bug
  669. has already been reported!  If you don't want to go public, send them
  670. to me: <guido@python.org>.
  671.  
  672.  
  673. Questions
  674. ---------
  675.  
  676. For help, if you can't find it in the manuals or on the web site, it's
  677. best to post to the comp.lang.python or the Python mailing list (see
  678. above).  If you specifically don't want to involve the newsgroup or
  679. mailing list, send questions to <python-help@python.org> (a group of
  680. volunteers which does *not* include me).  Because of my work and email
  681. volume, I'm often be slow in answering questions sent to me directly;
  682. I prefer to answer questions posted to the newsgroup.
  683.  
  684.  
  685. The Tk interface
  686. ----------------
  687.  
  688. Tk (the user interface component of John Ousterhout's Tcl language) is
  689. also usable from Python.  Since this requires that you first build and
  690. install Tcl/Tk, the Tk interface is not enabled by default.  Python
  691. supports all Tcl/Tk versions from version 7.5/4.1 through 8.0 (and it
  692. is expected that it will also work with newer versions).  Tcl/Tk
  693. 7.4/4.0 is no longer supported.  8.0 or any later non-alpha non-beta
  694. release is recommended.
  695.  
  696. See http://sunscript.sun.com/ for more info on Tcl/Tk, including the
  697. on-line manual pages.
  698.  
  699.  
  700. To enable the Python/Tk interface, once you've built and installed
  701. Tcl/Tk, load the file Modules/Setup in your favorite text editor and
  702. search for the string "_tkinter".  Then follow the instructions found
  703. there.  If you have installed Tcl/Tk or X11 in unusual places, you
  704. will have to edit the first line to fix or add -I and -L options.
  705. (Also see the general instructions at the top of that file.)
  706.  
  707. There is little documentation on how to use Tkinter; however most of
  708. the Tk manual pages apply quite straightforwardly.  Begin with
  709. fetching the "Tk Lifesaver" document,
  710. e.g. ftp://ftp.python.org/pub/python/doc/tkinter-doc.tar.gz (a gzipped
  711. tar file containing a PostScript file) or the on-line version
  712. http://www.python.org/doc/life-preserver/index.html.  Reading the
  713. Tkinter.py source will reveal most details on how Tkinter calls are
  714. translated into Tcl code.
  715.  
  716. A more recent introduction to Tkinter programming, by Fredrik Lundh,
  717. is at http://www.pythonware.com/library/tkinter/introduction/index.htm.
  718.  
  719. There are demos in the Demo/tkinter directory, in the subdirectories
  720. guido, matt and www (the matt and guido subdirectories have been
  721. overhauled to use more recent Tkinter coding conventions).
  722.  
  723. Note that there's a Python module called "Tkinter" (capital T) which
  724. lives in Lib/tkinter/Tkinter.py, and a C module called "_tkinter"
  725. (lower case t and leading underscore) which lives in
  726. Modules/_tkinter.c.  Demos and normal Tk applications only import the
  727. Python Tkinter module -- only the latter uses the C _tkinter module
  728. directly.  In order to find the C _tkinter module, it must be compiled
  729. and linked into the Python interpreter -- the _tkinter line in the
  730. Setup file does this.  In order to find the Python Tkinter module,
  731. sys.path must be set correctly -- the TKPATH assignment in the Setup
  732. file takes care of this, but only if you install Python properly
  733. ("make install libinstall").  (You can also use dynamic loading for
  734. the C _tkinter module, in which case you must manually fix up sys.path
  735. or set $PYTHONPATH for the Python Tkinter module.)
  736.  
  737.  
  738. Distribution structure
  739. ----------------------
  740.  
  741. Most subdirectories have their own README file.  Most files have
  742. comments.
  743.  
  744. Demo/           Demonstration scripts, modules and programs
  745. Doc/            Documentation (LaTeX sources)
  746. Grammar/        Input for the parser generator
  747. Include/        Public header files
  748. Lib/            Python library modules
  749. Makefile.in     Source from which config.status creates Makefile
  750. Misc/           Miscellaneous useful files
  751. Modules/        Implementation of most built-in modules
  752. Objects/        Implementation of most built-in object types
  753. PC/             PC porting files (DOS, Windows, OS/2)
  754. PCbuild/    Directory where you should build for Windows NT/95
  755. Parser/         The parser and tokenizer and their input handling
  756. Python/         The "compiler" and interpreter
  757. README          The file you're reading now
  758. Tools/          Some useful programs written in Python
  759. acconfig.h      Additional input for the autoheader program
  760. config.h.in     Source from which config.status creates config.h
  761. configure       Configuration shell script (GNU autoconf output)
  762. configure.in    Configuration specification (GNU autoconf input)
  763. install-sh      Shell script used to install files
  764.  
  765. The following files will (may) be created in the toplevel directory by
  766. the configuration and build processes:
  767.  
  768. Makefile        Build rules
  769. config.cache    cache of configuration variables
  770. config.h        Configuration header
  771. config.log      Log from last configure run
  772. config.status   Status from last run of configure script
  773. libpython1.5.a    The library archive
  774. python          The executable interpreter
  775. tags, TAGS      Tags files for vi and Emacs
  776.  
  777.  
  778. Author's address
  779. ================
  780.  
  781. Guido van Rossum
  782. CNRI
  783. 1895 Preston White Drive
  784. Reston, VA 20191
  785. USA
  786.  
  787. E-mail: guido@cnri.reston.va.us or guido@python.org
  788.  
  789.  
  790.  
  791. Copyright notice
  792. ================
  793.  
  794. The Python source is copyrighted, but you can freely use and copy it
  795. as long as you don't change or remove the copyright notice:
  796.  
  797. ----------------------------------------------------------------------
  798. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
  799. The Netherlands.
  800.  
  801.                         All Rights Reserved
  802.  
  803. Permission to use, copy, modify, and distribute this software and its
  804. documentation for any purpose and without fee is hereby granted,
  805. provided that the above copyright notice appear in all copies and that
  806. both that copyright notice and this permission notice appear in
  807. supporting documentation, and that the names of Stichting Mathematisch
  808. Centrum or CWI or Corporation for National Research Initiatives or
  809. CNRI not be used in advertising or publicity pertaining to
  810. distribution of the software without specific, written prior
  811. permission.
  812.  
  813. While CWI is the initial source for this software, a modified version
  814. is made available by the Corporation for National Research Initiatives
  815. (CNRI) at the Internet address ftp://ftp.python.org.
  816.  
  817. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  818. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  819. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  820. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  821. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  822. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  823. TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  824. PERFORMANCE OF THIS SOFTWARE.
  825. ----------------------------------------------------------------------
  826.  
  827.  
  828. --Guido van Rossum (home page: http://www.python.org/~guido/)
  829.